|
|
CharToPixel |
||||
| Header: | QuickdrawText.h | Carbon status: | Supported | |
Returns the screen pixel width from the left edge of a text segment to the glyph of the character whose byte offset you specify.
SInt16 CharToPixel (
Ptr textBuf,
SInt32 textLength,
Fixed slop,
SInt32 offset,
SInt16 direction,
JustStyleCode styleRunPosition,
Point numer,
Point denom
);
A pointer to the beginning of the text segment.
The length in bytes of the entire text segment pointed to by textBuf. The CharToPixel function requires the context of the complete text in order to determine the correct value.
The amount of slop for the text to be drawn. A positive value extends the text segment; a negative value condenses the text segment.
The value of this parameter is the number of pixels by which the width of the text segment is to be changed, after the text has been scaled. The slop is a signed value that specifies how much the text is to be extended or condensed. The slop is derived from the calculations made using the proportion returned from the PortionLine function for a style run. To measure or draw text that is not to be extended or condensed, pass a slop value of 0.
The offset from textBuf to the character within the text segment whose display pixel location is to be measured. For 2-byte script systems, if the character whose position is to be measured is 2 bytes long, this is the offset of the first byte.
This parameter specifies whether CharToPixel is to return the caret position for a character with a direction of left-to-right or right-to-left. A direction value of hilite indicates that CharToPixel is to use the caret position for the character direction that matches the primary line direction as specified by the SysDirection global variable.
The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.
This parameter specifies the position of the style run on the display line. It is used to determine the proportion of total slop to apply to a style run, measure or draw a line of justified text, identify where to break a line of text, and determine the caret position to mark an insertion point or highlight text.
The style run position parameter is meaningful only for those script systems that use intercharacter spacing for justification. For all other script systems, the parameter exists for future extensibility. Although the style run position parameter is not used, for example, for justifying text in the Roman script system, to allow for future compatibility, you should always specify the appropriate value for it for all calls that take it.
For those script systems that do use intercharacter spacing, space between style runs may be allocated differently depending upon whether the style run is leftmost, rightmost, or between two other style runs. For example, depending on the script system, if a style run occurs at the beginning or end of a line, extra space may not be added to the outer edge of the outermost glyph, whereas if a style run is interior to a line, all of the glyphs of the text may be treated the same: extra space is allocated to both sides of every glyph including those at either end of the style run.
The current implementations of simple script systems such as Roman and Cyrillic do not justify a line of text by changing the width of nonspace characters. Instead, they rely solely on the use of space characters: the same amount of extra width is added to (or subtracted from) every space whether the space is at the beginning or end of the line or interior to it.
A point giving the numerator for the horizontal and vertical scaling factors.
Both numer and denom are point values: numer specifies the numerator for the horizontal and vertical scaling factors, and denom specifies the denominator for the horizontal and vertical scaling factors. Together, these values specify the scaling factors for the text: numer.v over denom.v gives the vertical scaling (height), and numer.h over denom.h gives the horizontal scaling factors (width). You need to specify values for numer and denom even if you are not scaling the text. For unscaled text, you can specify scaling factors of 1, 1.
A point giving the denominator for the horizontal and vertical scaling factors.
The screen pixel width from the left edge of a text segment to the glyph of the character whose byte offset you specify.
You use CharToPixel to find the onscreen pixel location at which to draw a caret and to identify the selection points for highlighting. The CharToPixel function returns the horizontal distance in pixels from the start of the range of text beginning with the byte offset at textBuf to the glyph corresponding to the character whose byte offset is specified by the offset parameter. The pixel location is relative to the beginning of the text segment, not the left margin of the display line. To get the actual display line pixel location of the glyph relative to the left margin, you add the pixel value that CharToPixel returns to the pixel location at the end of the previous style run (on the left) in display order. In other words, you need to know the length of the text in pixels on the display line up to the beginning of the range of text that you call CharToPixel for, and then you add in the screen pixel width that CharToPixel returns.
You specify a value for textLen that is equal to the entire visible part of the style run on a line and includes trailing spaces if and only if they are displayed. They may not be displayed, for example, for the last style run in memory order, which is part of the line. Do not confuse the textLen parameter with the offset, which is the byte offset of the character within the text segment whose pixel location CharToPixel is to return.
If you use CharToPixel to get a caret position to mark the insertion point, you specify a value of leftCaret or rightCaret for the direction parameter. You can use the value of the PixelToChar leadingEdge flag to determine the direction parameter value.
If the leadingEdge flag is FALSE, you base the value of the direction parameter on the direction of the character at the byte offset in memory that precedes the one that PixelToChar returns; if leadingEdge is TRUE, you base the value of the direction parameter on the direction of the character at the byte offset that PixelToChar returns. If there isn’t a character at the byte offset, you base the value of the direction parameter on the primary line direction as determined by the SysDirection global variable.
Be sure to pass the same values for styleRunPosition and the scaling factors (numer and denom) to CharToPixel that you pass to any of the other justification functions for this style run.
The CharToPixel function works with text in all script systems. For 1-byte contextual script systems, CharToPixel calculates the widths of any ligatures, reversals, and compound characters that need to be drawn.
Note that textLen is the number of bytes to be drawn, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, do not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.
The CharToPixel function may move memory; do not call this function at interrupt time.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)